<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Futures</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Fiber">
<link rel="up" href="../synchronization.html" title="Synchronization">
<link rel="prev" href="channels/unbuffered_channel.html" title="Unbuffered Channel">
<link rel="next" href="futures/future.html" title="Future">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="channels/unbuffered_channel.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../synchronization.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="futures/future.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="fiber.synchronization.futures"></a><a class="link" href="futures.html" title="Futures">Futures</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="futures/future.html">Future</a></span></dt>
<dt><span class="section"><a href="futures/promise.html">Template
        <code class="computeroutput"><span class="identifier">promise</span><span class="special">&lt;&gt;</span></code></a></span></dt>
<dt><span class="section"><a href="futures/packaged_task.html">Template
        <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special">&lt;&gt;</span></code></a></span></dt>
</dl></div>
<h5>
<a name="fiber.synchronization.futures.h0"></a>
        <span><a name="fiber.synchronization.futures.overview"></a></span><a class="link" href="futures.html#fiber.synchronization.futures.overview">Overview</a>
      </h5>
<p>
        The futures library provides a means of handling asynchronous future values,
        whether those values are generated by another fiber, or on a single fiber
        in response to external stimuli, or on-demand.
      </p>
<p>
        This is done through the provision of four class templates: <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> and
        <a class="link" href="futures/future.html#class_shared_future"><code class="computeroutput">shared_future&lt;&gt;</code></a> which are used to retrieve the asynchronous
        results, and <a class="link" href="futures/promise.html#class_promise"><code class="computeroutput">promise&lt;&gt;</code></a> and <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> which
        are used to generate the asynchronous results.
      </p>
<p>
        An instance of <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> holds the one and only reference
        to a result. Ownership can be transferred between instances using the move
        constructor or move-assignment operator, but at most one instance holds a
        reference to a given asynchronous result. When the result is ready, it is
        returned from <a class="link" href="futures/future.html#future_get"><code class="computeroutput">future::get()</code></a> by rvalue-reference to allow the result
        to be moved or copied as appropriate for the type.
      </p>
<p>
        On the other hand, many instances of <a class="link" href="futures/future.html#class_shared_future"><code class="computeroutput">shared_future&lt;&gt;</code></a> may
        reference the same result. Instances can be freely copied and assigned, and
        <a class="link" href="futures/future.html#shared_future_get"><code class="computeroutput">shared_future::get()</code></a>
returns a <code class="computeroutput"><span class="keyword">const</span></code>
        reference so that multiple calls to <a class="link" href="futures/future.html#shared_future_get"><code class="computeroutput">shared_future::get()</code></a>
are
        safe. You can move an instance of <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> into an instance
        of <a class="link" href="futures/future.html#class_shared_future"><code class="computeroutput">shared_future&lt;&gt;</code></a>, thus transferring ownership
        of the associated asynchronous result, but not vice-versa.
      </p>
<p>
        <a class="link" href="futures/future.html#fibers_async"><code class="computeroutput">fibers::async()</code></a> is a simple way of running asynchronous tasks.
        A call to <code class="computeroutput"><span class="identifier">async</span><span class="special">()</span></code>
        spawns a fiber and returns a <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> that will deliver
        the result of the fiber function.
      </p>
<h5>
<a name="fiber.synchronization.futures.h1"></a>
        <span><a name="fiber.synchronization.futures.creating_asynchronous_values"></a></span><a class="link" href="futures.html#fiber.synchronization.futures.creating_asynchronous_values">Creating
        asynchronous values</a>
      </h5>
<p>
        You can set the value in a future with either a <a class="link" href="futures/promise.html#class_promise"><code class="computeroutput">promise&lt;&gt;</code></a> or
        a <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a>. A <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> is
        a callable object with <code class="computeroutput"><span class="keyword">void</span></code>
        return that wraps a function or callable object returning the specified type.
        When the <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> is invoked, it invokes the
        contained function in turn, and populates a future with the contained function's
        return value. This is an answer to the perennial question: <span class="quote">&#8220;<span class="quote">How do
        I return a value from a fiber?</span>&#8221;</span> Package the function you wish to run
        as a <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> and pass the packaged task to
        the fiber constructor. The future retrieved from the packaged task can then
        be used to obtain the return value. If the function throws an exception,
        that is stored in the future in place of the return value.
      </p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">calculate_the_answer_to_life_the_universe_and_everything</span><span class="special">()</span> <span class="special">{</span>
    <span class="keyword">return</span> <span class="number">42</span><span class="special">;</span>
<span class="special">}</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">packaged_task</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">()&gt;</span> <span class="identifier">pt</span><span class="special">(</span><span class="identifier">calculate_the_answer_to_life_the_universe_and_everything</span><span class="special">);</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">future</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">fi</span><span class="special">=</span><span class="identifier">pt</span><span class="special">.</span><span class="identifier">get_future</span><span class="special">();</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">pt</span><span class="special">)).</span><span class="identifier">detach</span><span class="special">();</span> <span class="comment">// launch task on a fiber</span>

<span class="identifier">fi</span><span class="special">.</span><span class="identifier">wait</span><span class="special">();</span> <span class="comment">// wait for it to finish</span>

<span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">is_ready</span><span class="special">());</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_value</span><span class="special">());</span>
<span class="identifier">assert</span><span class="special">(!</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_exception</span><span class="special">());</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">get</span><span class="special">()==</span><span class="number">42</span><span class="special">);</span>
</pre>
<p>
        A <a class="link" href="futures/promise.html#class_promise"><code class="computeroutput">promise&lt;&gt;</code></a> is a bit more low level: it just provides explicit
        functions to store a value or an exception in the associated future. A promise
        can therefore be used where the value might come from more than one possible
        source.
      </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">promise</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">pi</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">future</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">fi</span><span class="special">;</span>
<span class="identifier">fi</span><span class="special">=</span><span class="identifier">pi</span><span class="special">.</span><span class="identifier">get_future</span><span class="special">();</span>

<span class="identifier">pi</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="number">42</span><span class="special">);</span>

<span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">is_ready</span><span class="special">());</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_value</span><span class="special">());</span>
<span class="identifier">assert</span><span class="special">(!</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_exception</span><span class="special">());</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">get</span><span class="special">()==</span><span class="number">42</span><span class="special">);</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="channels/unbuffered_channel.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../synchronization.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="futures/future.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
